ODDraft

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODDraft

Superclasses
ODRefCntObject --> ODObject
Subclasses
none

An object of the ODDraft class represents a particular version of a document object.

Description
The ODDraft class is implemented differently for different platforms and storage mechanisms.
The set of related classes, ODContainer (page 98), ODDocument (page 132), ODDraft, and ODStorageUnit (page 664) is called a container suite. Container suite classes are implemented as an integrated set for each platform and storage mechanism because they work intimately with one another at many levels. The container suite used by default on the Mac OS platform is the Bento container suite.
An OpenDoc document can contain one or more drafts and each draft can contain one or more storage units. Each document, draft, and storage unit has a unique ID. If a storage unit is used to store data for a persistent object, the storage unit's ID is also used as the ID of the persistent object.
Because each draft corresponds to a version of its document, a document can be defined as a collection of versioned drafts. The document shell or container application creates or accesses a draft of a document by calling the CreateDraft (page 139), AcquireDraft (page 136), and AcquireBaseDraft (page 134) methods of that document.
Each draft has permissions that control access to it. Drafts are created with exclusive read/write permissions. The document shell or container application can change a draft's permissions when it calls the document's AcquireDraft and AcquireBaseDraft methods. Access to a draft is guaranteed to be exclusive only if the draft has exclusive read/write permissions. Many methods of ODDraft require a particular kind of access to the draft; for example, the CreateFrame method requires write access. Before calling one of these methods, you should call the draft's GetPermissions method (page 173) and check that the draft's current permissions allow the required access.
Drafts are linearly derived in a document. The drafts of a document can be thought of as a stack; the oldest draft, called the base draft, is at the bottom of the stack and the most recent is at the top. Although part editors can access any draft of a document, only the most recent (topmost) draft can be modified; all earlier drafts are read only.
The ODDraft class has a set of CreateClass and AcquireClass methods for creating and retrieving persistent objects of various classes: parts, frames, link objects, and link-source objects. For example, the CreateFrame method (page 164) creates a new frame object matching the specifications you provide; the AcquireFrame method (page 153) re-creates the ODFrame object stored in the specified storage unit.
Many OpenDoc methods modify the content of a draft, and therefore the draft must be notified so that it can save these changes. If this draft contains no changes since it was last saved, it is said to be clean; if it contains changes, it is said to be dirty. For example, after a successful call to the CreateFrame method, the draft is dirty. You can call the SetChangedFromPrev method (page 184) when your part's content has changed; that method marks the draft as dirty so that content changes will be saved.
You can copy or clone the persistent objects in a draft into a specified storage unit. All cloning must be performed within a transaction; the Bento container suite allows only one cloning transaction at any given time.

To initiate a cloning transaction, call the draft's BeginClone method (page 159). This method returns a unique draft key that identifies the transaction.
To copy a persistent object, call the draft's Clone method (page 162), passing as parameters the draft key returned by the BeginClone method, the ID of the object to be cloned, the ID of the destination storage unit, and the ID of the frame object specifying the scope of the cloning operation.
To commit the cloning transaction, call the draft's EndClone method (page 171). Until the EndClone method has successfully executed, there is no guarantee that all the objects have been copied.
To terminate the transaction unsuccessfully, call the draft's AbortClone method (page 151). You should call this method if the cloning operation cannot be completed for any reason.

For more information on how ODDraft and other container-suite classes are used, see the chapters on storage and OpenDoc runtime features in the OpenDoc Programmer's Guide for the MacOS.

Methods
This section presents summary descriptions of the ODDraft methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [D] are called only by the document shell or container applications.
Draft Characteristics

GetDocument [D]
Returns a reference to the document object that created this draft.
AcquireDraftProperties
Returns a reference to the storage unit in which this draft stores its properties and data that are global to this draft.
GetID [D]
Returns the draft ID of this draft.
IsValidID
Returns a Boolean value that indicates whether the specified object ID is valid.
GetPermissions
Returns this draft's current permissions.
GetPersistentObjectID
Returns the scripting ID of the specified part or frame.
AcquirePersistentObject
Returns a reference to the part or frame with the specified scripting ID.
Object Factory Methods

CreateFrame
Creates a new frame in this draft.
AcquireFrame
Returns a reference to the frame whose data is stored in the specified storage unit.
AcquireLink
Returns a reference to the link object whose data is stored in the specified storage unit or that can be constructed from the given link specification.
CreateLinkSource
Creates a new link-source object in this draft.
AcquireLinkSource
Returns a reference to the link-source object whose data is stored in the specified storage unit.
CreateLinkSpec
Creates a link-specification object for the specified part.
CreatePart
Creates a new part in this draft.
AcquirePart
Returns a reference to the part whose data is stored in the specified storage unit.
CreateStorageUnit
Creates a new storage unit in this draft.
AcquireStorageUnit
Returns a reference to the storage unit with the specified ID.
Cloning

BeginClone
Initiates a cloning transaction to transfer data from this draft to the specified destination draft.
Clone
Clones the specified persistent object or storage unit.
WeakClone
Ensures that, if the specified object is cloned, weak persistent references to it are maintained.
EndClone
Commits the specified cloning transaction.
AbortClone
Aborts the specified cloning transaction.
Modifying Drafts

Externalize [D]
Writes to storage all persistent objects and storage units of this draft object.
RemoveChanges [D]
Removes all changes made in this draft.
RemoveFromDocument [D]
Removes this draft from its document and destroys this draft.
ReleasePart
Releases the specified part of this draft.
SaveToAPrevious [D]
Copies the content of this draft to the specified previous draft of the same document.
ChangedFromPrev [D]
Returns a Boolean value that indicates whether this draft contains any changes from the previous draft.
SetChangedFromPrev
Marks this draft as dirty.
Internal Methods

RemoveFrame
Removes the specified frame from this draft.
RemoveLink
Removes the specified link object from this draft.
RemoveLinkSource
Removes the specified link-source object from this draft.
RemovePart
Removes the specified part from this draft.
RemoveStorageUnit
Removes the specified storage unit from this draft.

Methods
AbortClone
AcquireDraftProperties
AcquireFrame
AcquireLink
AcquireLinkSource
AcquirePart
AcquirePersistentObject
AcquireStorageUnit
BeginClone
ChangedFromPrev
Clone
CreateFrame
CreateLinkSource
CreateLinkSpec
CreatePart
CreateStorageUnit
EndClone
Externalize
GetDocument
GetID
GetPermissions
GetPersistentObjectID
IsValidID
ReleasePart
RemoveChanges
RemoveFrame
RemoveFromDocument
RemoveLink
RemoveLinkSource
RemovePart
RemoveStorageUnit
SaveToAPrevious
SetChangedFromPrev
WeakClone